﻿/*********************************************************************
 *
 *                             NOTICE
 *               COPYRIGHT (c) 2012 Panoscopix Software, Inc.
 *                UNPUBLISHED - ALL RIGHTS RESERVED
 * 
 *      This program is confidential, proprietary, and a trade
 *   secret of Panoscopix Software, Inc. The receipt or possession of
 *     this program does not convey any rights to reproduce or
 *      disclose its contents, or to manufacture, use, or sell
 *       anything that it may describe, in whole or in part, 
 *   without the specific written consent of Panoscopix Software, Inc.
 *
 * Interface for the Command Stack.  A LIFO queue for Commands.
 * 
 *******************************************************************/
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace FileSystem
{
    interface ICommandStack
    {
        /// <returns>Number of commands on this stack.</returns>
        int size();

        /// <returns>size() == 0.</returns>
        bool isEmpty();

        /// <summary>
        /// Pushes the supplied Command onto the stack; first one to be removed
        /// with pop().
        /// </summary>
        /// <param name="c">Command to push.  Ignored if NULL.</param>
        void push(ICommand c);

        /// <summary>
        /// Pops the current top of the stack (removes it) and returns it.
        /// </summary>
        /// <returns>Popped Command, or NULL if isEmpty().</returns>
        ICommand pop();

        /// <summary>
        /// Removes all items, if any, from the stack.  On return, isEmpty() == true.
        /// </summary>
        void clear();

        /// <summary>
        /// Write a description string for this object (and embedded objects) using context.
        /// </summary>
        /// <param name="context">PrintContext (indent level) for the description.</param>
        /// <returns>String describing this command (including state), using context.</returns>
        String describe(IPrintContext context);
    }
}
